<!--
 ~ Copyright (C) 2015 CS SI
 ~
 ~ This program is free software; you can redistribute it and/or modify it
 ~ under the terms of the GNU General Public License as published by the Free
 ~ Software Foundation; either version 3 of the License, or (at your option)
 ~ any later version.
 ~ This program is distributed in the hope that it will be useful, but WITHOUT
 ~ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 ~ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
 ~ more details.
 ~
 ~ You should have received a copy of the GNU General Public License along
 ~ with this program; if not, see http://www.gnu.org/licenses/
 ~
-->
<html>
<head>
    <title>Standalone Tool Adapter</title>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    <link rel="stylesheet" href="../style.css">
</head>

<body>
<table class="header">
    <tr class="header">
        <td class="header">&nbsp;
            Standalone Tool Adapter - Editing adapters
        </td>
        <td class="header" align="right"><a href="nbdocs://org.esa.snap.snap.help/org/esa/snap/snap/help/docs/general/overview/SnapOverview.html"><img src="../images/snap_header.jpg"
                                                                                     border=0></a>
        </td>
    </tr>
</table>

<h4>Creating a new adapter or modifying an existing one</h4>
<p>The form for creating a new adapter is reused for editing an existing adapter and for duplicating an adapter.</p>
<!-- <img src="../images/EditAdapter.png"/> -->
<p>The form is structured into multiple areas:</p>
<ul>
    <li>descriptor details</li>
    <li>system variables</li>
    <li>pre-processing</li>
    <li>configuration</li>
    <li>tool output patterns</li>
    <li>parameters</li>
</ul>
<p>For details about the operator structure and what is the use of each member, see <a href="user_interface.html">here</a>.</p>
<h5>Descriptor details</h5>

<img src="../images/OperatorDescriptor.png"/>

<p>This area consists in the following fields:</p>
<ul>
    <li>Alias: a short name for the adapter to distinguish from the rest of the adapters, this alias will be used to
        name the folder on disk where the operator resides, so special characters should not be used (for example,
        on windows, the following characters are not allowed when defining a folder name: <>:"/\|?*). This is a
        required field.</li>
    <li>Unique Name: this name is a name which registers the adapter in the toolbox. It must be unique. This is a
        required field.</li>
    <li>Label: is the user-friendly name. This field is not required.</li>
    <li>Version:</li>
    <li>Copyright:</li>
    <li>Authors:</li>
    <li>Description:</li>
    <li>Menu Location: this represents the path to the menu where the tool shortcut will be placed. The user can choose
        between placing the adapter action in one of the already existing menus, or to create a new menu.
    </li>
</ul>
<h5>System variables</h5>

<img src="../images/SystemVariables.png"/>

<p>System variables are values that must be set when the tools is executed. Such a variable
    may or may not be a system-wide variable (eg. one set in Environment Variables on Windows OS). If the latter case,
    the system value will always replace the user-defined value.
    The value of a system variable (in the context of Standalone Tool Adapter) can be shared across adapters, with the
    condition it is defined in each such adapter. For example, if two adapters declare the same $VAR variable, it is
    enough to edit its value in one of the adapters, and it will be automatically reflected in the other adapter.</p>
<p>There are two types of variables:
    <ul>
        <li>Simple variables, that only have one value;</li>
        <li>System-dependent variables, that allow setting values for the three operating systems supported (Windows, Linux and MacOSX).
        This kind of variables is necessary, for example, when you'd like to create a single adapter that can be used on either OS, but
        there are just a few elements that are different among OSes (like, for example, the shell script extension: .bat on Windows,
        .sh on Linux and MacOSX).</li>
    </ul>
    A new variable can be added by pressing one of the <b>+ Add Variable</b> or <b>+ Add System-Dependent Variable</b> buttons and an
    existing one can be deleted by using the delete button (<b>X</b>) in the left of the desired variable.
    The key and value of an variable can be edited by double-clicking the corresponding cell. Simple variables can be edited in place,
    while for editing system-dependent variables the following small form is used:<br/>
    <img src="../images/SystemDependentVariable.png"/>
</p>
<h5><b>Pre-processing</b> area contains 2 field, each one with a checkbox and a combobox:</h5>

<img src="../images/Preprocessing.png"/>

<ul>
    <li>Pre-processing tool: when this option is checked and an already defined tool is chosen in the combobox,
        that tool is executed with the same input parameters values as the current tool, as the first step of the
        execution of the current adapter.</li>
    <li>Write before pre-processing: when this option is checked and a writer is selected in the combobox, the product
        is written to disk as the second step of the execution of the current adapter. The path where the product is
        saved is given as the value of the parameter <i>sourceProductFile</i></li>
</ul>
<h5>Configuration parameters includes:</h5>

<img src="../images/ConfigurationParameters.png"/>

<ul>
    <li>Tool location: location of the executable file corresponding to the tool. The location can be expressed in one of the following forms:
        <ul>
            <li>Just the executable name (and extension), with the condition that it is already added to system path;</li>
            <li>A path expressed by means of one of the defined system variables and the executable name (and extension);</li>
            <li>The full path of the executable (including its name and extension).</li>
        </ul>
    </li>
    <li>Working directory: the place where the temporary files are saved. One can use one of the define system variables to set its value.</li>
    <li>Tool handles the output name: whether the tool needs the name of the output product, or it produces it by itself.</li>
    <li>Command line template: the velocity template to be executed, including the command line arguments of the tool,
        each one of them on a separate line. The content of the template is saved in a file called
        <i>&lt;operator_alias&gt;_template.vm</i> under the folder of the operator.</i><br/>
        To use parameters and system variables in the velocity template, you have to prepend their names with the dollar
        sign ('<b>$</b>'). To minimize the spelling errors when typing parameters, when pressing '<b>$</b>' a suggestion
        list will be displayed, containing all the parameter and variable names, lexicographically sorted:<br/>
        <img src="../images/Autocomplete.png"/>
    </li>
</ul>
<p>Note: all the values of the parameters of type File (the tool location, the working directory, and any other File (or File List) type parameter that
is marked as 'Not Null' or 'Not Empty' will be checked for pointing to existing files or folders when pressing the OK button.</p>
<h5>Tool output patterns</h5>
<p>Tool output patterns includes 2 defined patterns for determining the progress of the tool and also the
    error status. When the tool outputs something, the two patterns are checked and if one of them matches the output,
    this is registered in the log (in SNAP application, when the Console is active, the log messages will appear
    in the console view)</p>

<h5>Operator parameters</h5>

<img src="../images/OperatorParameters.png"/>

<p>This area consists in a table of parameters necessary for the processing of the velocity template. Each parameter
    can have the following properties:</p>
<ul>
    <li>name</li>
    <li>description</li>
    <li>label</li>
    <li>data type</li>
    <li>default value</li>
</ul>
<p>The data type of a parameter can be as follows:</p>
<table>
    <tr>
        <th>Type</th><th>Description</th><th>Special use-case</th>
    </tr>
    <tr>
        <td>Integer</td><td>Integer values</td><td>N/A</td>
    </tr>
    <tr>
        <td>Decimal</td><td>Float values</td><td>N/A</td>
    </tr>
    <tr>
        <td>String</td><td>A list of characters</td><td>N/A</td>
    </tr>
    <tr>
        <td>Boolean</td><td>The control of this type is a checkbox, so the accepted values are true and false.</td>
        <td>N/A</td>
    </tr>
    <tr>
        <td>List</td><td>This type represents a list of strings, delimited by comma.</td><td>N/A</td>
    </tr>
    <tr>
        <td>File</td><td>This type represents a file.</td><td>N/A</td>
    </tr>
    <tr>
        <td>Folder</td><td>This type represents a folder.</td><td>N/A</td>
    </tr>
    <tr>
        <td>Template Parameter</td>
        <td>The template parameters are velocity templates that need to be interpreted
            before the execution of the tool. The interpreted result will be saved on local disk, in the temporary folder
            of the adapter. The full path of the result file will be saved as this parameter's value, so when the parameter is
            used in the tool template, it will be replaced with the full path of the interpreted result.</td>
        <td>N/A</td>
    </tr>
    <tr><td>Template Before</td>
        <td>This is a velocity template which will be interpreted before the execution of the tool.</td>
        <td>It can be used to create/copy some files necessary for the execution, or to...</td>
    </tr>
    <tr>
        <td>Template After</td><td>This is a velocity template which will be executed after the tool execution.</td>
        <td>It can be used to delete some temporary files that were used to the actual execution (for example
            temporary products - see ... parameter type), or to do some operations with the result of the execution
            (like renaming the file containing the final product)
        </td>
    </tr>
    <tr>
        <td>Product List</td>
        <td>Represents a product loaded in SNAP application context (or a list of loaded products)</td>
        <td>This type is not available in the parameter type combobox, instead only the default parameter called
            'sourceProduct' has this type (see section <b>Default parameters</b>)</td>
    </tr>
    <tr>
        <td>File List</td>
        <td>Represents a file or a list of files</td>
        <td>This type is not available in the parameter type combobox, instead only the default parameter called
            'sourceProductFile' has this type (see section <b>Default parameters</b>)</td>
    </tr>
</table>

<h5>Default (read-only) parameters</h5>
<p>An adapter must have 3 parameters. If the descriptor of the adapter does not contain one or all of this parameters,
    they are added when the editing form is launched. Those parameters are:</p>
<ul>
    <li>
        sourceProduct - represents the product(s) choosed by the user from the ones loaded in SNAP context on the
        time of the execution (see <b>Executing an adapter</b> for details about how to choose a product). When this
        parameter is used in the velocity template, for each product the method <b>getFileLocation()</b> is called, and
        the path returned by the method is passed to the velocity template. If there are multiple source products,
        each one is accessed by using the syntax sourceProduct[0], sourceProduct[1], ... This parameter cannot be
        edited or deleted.
    </li>
    <li>
        sourceProductFile - this is a File or a list of files corresponding to the source products chosed on execution.
        This is used only if 'Write product with' is checked and a writer is chosed. When this happens, all the source
        products are written on disk, in the temporary folder, and the absolute path of the file(s) is stored in
        this parameter, so it can be used in the velocity template. This parameter cannot be edited or deleted.
    </li>
    <li>
        targetProductFile - this is a File corresponding to the target product that will be loaded in SNAP context
        after the tool execution. This parameter cannot be deleted or edited, but his value can be edited (the default value
        and also the value on execution).
    </li>
</ul>
<h5>Regular parameters</h5>
<p>All user-defined parameters that are not default parameters or template parameters are considered as regular
    parameters. The type of those parameters can be: Integer, Decimal, String, Boolean, List. Those parameters can be
    edited by pressing the corresponding 'Ellipsis' (...) button. This will open a new form, where the following
    properties of the parameter can be changed:</p>
<ul>
    <li>Name</li>
    <li>Alias</li>
    <li>Type</li>
    <li>Default value</li>
    <li>Description</li>
    <li>Label</li>
    <li>Unit</li>
    <li>Interval</li>
    <li>Value set</li>
    <li>Condition</li>
    <li>Pattern</li>
    <li>Format</li>
    <li>Not null</li>
    <li>Not empty</li>
    <li>Alias</li>
    <li>Deprecated</li>
</ul>
<img src="../images/RegularParamEditor.png"/>
<h5>Template parameters</h5>
<p>The template parameters are parameters that represent a velocity template stored in a file on disk. So this is
    actually a parameter, having the type File, on which you can pass other regular parameters.</p>
<p>When editing this type of parameter, first a file must be chosed, and then the template gets loaded in the form and
    some new parameters can be defined for this template:</p>
<img src="../images/TemplateParamEditor.png"/>
<p>This template will be interpreted in 3 key moments of the execution:</p>
<ul>
    <li>If the parameter type is <i>Template Before</i>, the template gets interpreted before any of the execution
        steps of the toll gets started.
    </li>
    <li>If the parameter type is <i>Template Parameter</i>, the template gets interpreted on strating the execution
        of the tool. In this case, the result is saved in the working directory, and the full path to the file gets
        saved in this parameter's value.
    </li>
    <li>If the parameter type is <i>Template After</i>, the template gets interpreted after the execution
        steps of the toll, as the final step. The result is also saved in the working directory.
    </li>
</ul>

<h5>Bundled Binaries</h5>
<img src="../images/BundledBinaries.png"/>

<p>In this tab the user can integrate an installer in the adapter. When the adapter is downloaded/installed, the user can install also manually the tool.
    In case of a remote installer, installing the tool actually means downloading the installer from the given URL and copying it on a local address.
    After the tool is installed in the target folder (as configured in the adapter), all the adapter parameters and variables should be valid.
The tool can be configured to be install on Windows, Linux and MaxOSX</p>

<p>This area consists in the following fields:</p>
<ul>
    <li> Type: there are two options to choose, Zip archive (must be Self-Extracting Zip file) or installer. </li>
    <li> Location: if Local is selected, the Source File field should contain the local address of the installer or of the zip archive. Otherwise, if Remote is selected,
        the URL field should contain the address of the installer or the zip archive that will be downloaded.</li>
    <li> Arguments: the arguments used to install the Self-Extracting archive. </li>
    <li> Target Location: the location where the user wants to install the tool. </li>
    <li> Reflect in Variable: the user can choose an already existing variable, which will have as value the location where the tool was installed. </li>
</ul>

<hr>
</body>
</html>
